Migration Guide: Hotel uAPI to Hotel JSON API

Introduction

This migration guide assists developers in transitioning from the legacy Travelport Universal API (uAPI) SOAP-based hotel booking flow to the modern Hotel JSON API. The JSON API provides a RESTful interface with simplified request/response structures and improved performance.

Key Benefits of the JSON API:

• REST/JSON instead of SOAP/XML - simpler integration

• OAuth 2.0 authentication instead of WS-Security

• Cleaner, more intuitive data structures

• Better error handling with standard HTTP status codes

• Consolidated endpoints reduce complexity

• Two workflow options: v11 (multi-step) or SearchComplete (single call)

Important: This guide covers migration to the Hotel JSON API, which has two versions:

• Hotel JSON API v11 - Multi-step workflow (Search > Availability > Rules)SearchComplete

• API - Single consolidated endpoint (recommended)

This guide shows both paths so you can choose the best approach for your needs.

Overview of uAPI Hotel Booking Flow

As a quick refresher, uAPI is a SOAP-based API using XML payloads:

Key Characteristics:

• Protocol: SOAP over HTTP

• Data Format: XML

• Authentication: WS-Security headers

• Multiple SOAP actions for different operations

• Complex nested XML structures

• Property details require separate call

Overview of Hotel JSON API

The Hotel JSON API is a modern RESTful API with two workflow options:

Option 1: JSON API v11 (Multi-Step Workflow)

Option 2: SearchComplete (Single Call)

JSON API Characteristics:

• Protocol: RESTful HTTP

• Data Format: JSON

• Authentication: OAuth 2.0 Bearer tokens

• Consolidated RESTful endpoints

• Simplified request/response structures

• Property details included in search response

• Standard HTTP status codes for errors

Key Differences Between uAPI and JSON API

Summary Comparison

Authentication Migration

uAPI Authentication

uAPI uses WS-Security with username/password in SOAP headers:

<soap:Header>
  <wsse:Security>
    <wsse:UsernameToken>
      <wsse:Username>USERNAME</wsse:Username>
      <wsse:Password>PASSWORD</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
  <Header_v52_0:BranchCode>P1234567</Header_v52_0:BranchCode>
</soap:Header>

JSON API Authentication

JSON API uses OAuth 2.0. First, obtain an access token (see Authentication):

Then use the token in all API requests:

Key Differences:

• OAuth tokens expire in 24 hours and must be refreshed

• Access group (PCC) is now in XAUTH_TRAVELPORT_ACCESSGROUP header

• No username/password in each authorization request - use token instead

• Token management required (cache tokens, refresh before expiry)

Migration Path 1: JSON API v11 (Multi-Step Workflow)

This section shows how to migrate several uAPI calls to the JSON API v11 endpoints. This maintains the familiar multi-step workflow while modernizing the technology.

Step 1: Hotel Search

uAPI: HotelSearchAvailabilityReq

<soapenv:Envelope>
    <soapenv:Body>
        <hot:HotelSearchAvailabilityReq>
            <com:BillingPointOfSaleInfo OriginApplication="UAPI"/>
            <hot:HotelSearchLocation>
                <hot:HotelLocation Location="SFO"/>
            </hot:HotelSearchLocation>
            <hot:HotelSearchModifiers>
                <hot:NumberOfAdults>2</hot:NumberOfAdults>
            </hot:HotelSearchModifiers>
            <hot:HotelStay>
                <hot:CheckinDate>2025-03-15</hot:CheckinDate>
                <hot:CheckoutDate>2025-03-17</hot:CheckoutDate>
            </hot:HotelStay>
        </hot:HotelSearchAvailabilityReq>
    </soapenv:Body>
</soapenv:Envelope>

JSON API v11:

{
 "PropertiesQuerySearch": {
  "@type": "PropertiesQuerySearch",
  "CheckInDate": "2025-03-15",
  "CheckOutDate": "2025-03-17",
  "SearchBy": {
   "@type": "SearchByIATACode",
   "IATACode": "SFO"
  },
  "RoomStayCandidate": [
   {
    "GuestCount": {
     "AdultCount": 2
    }
   }
  ]
 }
}

Key Changes:

• JSON instead of XML - simpler structure

• SearchBy object for location (supports coordinates, city, airport)

• RoomStayCandidate replaces HotelSearchModifiers

• Property details (images, amenities) included in response

• No separate HotelDetailsReq needed

Step 2: Hotel Availability

uAPI: Availability Included in Search

In uAPI, availability is returned in the HotelSearchAvailabilityReq response.

JSON API v11: Hotel Availability API

JSON API v11 requires a separate availability call:

{
 "CatalogOfferingsQueryHospitality": {
  "@type": "CatalogOfferingsQueryHospitality",
  "PropertyIdentifier": [
   "TVPT-12345",
   "TVPT-67890"
  ],
  "HotelStay": {
   "CheckInDate": "2025-03-15",
   "CheckOutDate": "2025-03-17"
  },
  "GuestCount": {
   "AdultCount": 2
  }
 }
}

Key Changes:

• Separate call required (different from uAPI)

• Use PropertyIdentifier from search response

• Returns CatalogOfferingIdentifier needed for rules call

• Rate and room details in response

Step 3: Rate Rules

uAPI: HotelRulesReq

<soapenv:Envelope>
    <soapenv:Body>
        <hot:HotelRulesReq>
            <com:BillingPointOfSaleInfo OriginApplication="UAPI"/>
            <hot:HotelReservationLocatorCode>ABC123</hot:HotelReservationLocatorCode>
            <hot:HotelRulesModifiers>
                <hot:HotelRulesLookup>RatePlanType</hot:HotelRulesLookup>
            </hot:HotelRulesModifiers>
        </hot:HotelRulesReq>
    </soapenv:Body>
</soapenv:Envelope>

JSON API v11:

{
 "BuildFromCatalogOfferingsRequestHospitality": {
  "CatalogOfferingIdentifier": "abc123-def456-ghi789"
 }
}

Key Changes:

• Use CatalogOfferingIdentifier from availability response

• Returns cancellation policies, deposit requirements, guarantees

• Simpler JSON structure vs XML

• More detailed policy information

Migration Path 2: SearchComplete (Single Call)

Recommended Approach

SearchComplete consolidates search, availability, and rules into a single endpoint. This is the recommended approach for new implementations as it reduces complexity and improves performance.

uAPI: Three Separate SOAP Calls

In uAPI, you make:

• HotelSearchAvailabilityReq - Search and get basic availability

• HotelDetailsReq - Get property details

• HotelRulesReq - Get rate rules and policiesSearchComplete

Single REST Call

One call replaces all three

{
 "stayDetails": {
  "checkInDateLocal": "2025-03-15",
  "checkOutDateLocal": "2025-03-17",
  "guests": {
   "numberOfAdults": 2,
   "numberOfChildren": 0
  }
 },
 "propertyFilter": {
  "location": {
   "iataCode": "SFO"
  },
  "returnOnlyAvailableProperties": true,
  "returnRateSummaryInfo": true
 },
 "requestedCurrency": "USD"
}

What You Get Back:

• Properties with all details (name, address, amenities, images)

• Available rates with complete pricing

• Room type information

• Rate rules including cancellation and deposit policies

• All in one unified JSON response

Benefits vs uAPI:

• One API call instead of three - reduced latency

• No need to manage state between calls

• Simpler error handling (one point of failure)

• Cleaner JSON structure vs XML

• Built-in caching for better performance

Booking Workflow Changes

The booking, retrieval, modification, and cancellation flows are similar between uAPI and JSON API, with the main differences being REST/JSON vs SOAP/XML format.

Create Booking

Key Changes:

• Use propertyKey and rateKey from search response

• Payment object structure simplified

• Guest details in cleaner JSON format

• Response includes reservation confirmation immediately

Retrieve Booking

Key Changes:

• RESTful GET instead of SOAP request

• Confirmation ID in URL path

• Complete reservation details in JSON response

• Standardized status codes

Modify Booking

Key Changes:

• RESTful PUT for updates

• Send only changed fields

• Response includes updated reservation

• Clearer modification rules and restrictions

Cancel Booking

Key Changes:

• RESTful DELETE for cancellation

• Cancellation penalties clearly shown in response

• Standard HTTP status codes for success/failure

• Detailed cancellation confirmation

General Changes and Considerations

Error Handling

JSON API error response example:

{
 "errors": [
  {
   "code": "INVALID_REQUEST",
   "message": "Check-in date must be in the future",
   "field": "stayDetails.checkInDateLocal"
  }
 ]
}

Request/Response Size

JSON API payloads are typically 40-60% smaller than equivalent SOAP/XML:

• Faster transmission over network

• Reduced bandwidth costs

• Easier to parse and process

• More human-readable for debugging

Development Tools

Performance Improvements

• OAuth token caching reduces authentication overhead

• JSON parsing is faster than XMLSearchComplete

• API includes intelligent caching

• RESTful architecture enables better CDN usage

• Smaller payload sizes improve network performance

Migration Strategy Recommendations

• Phase 1: Set up OAuth 2.0 authentication and test token management

• Phase 2: Migrate search functionality (choose v11 or SearchComplete)

• Phase 3: Test search thoroughly with various criteria

• Phase 4: Migrate booking workflow (create, retrieve, modify, cancel)

• Phase 5: Update error handling for HTTP status codes

• Phase 6: Performance testing and optimization

• Phase 7: Production cutover with monitoring

Conclusion

Migrating from uAPI to the Hotel JSON API modernizes your integration with significant benefits:

Technical Benefits:

• Simpler REST/JSON architecture vs SOAP/XML

• Modern OAuth 2.0 authentication

• Smaller payloads and faster performance

• Better development tools and documentation

• Standard HTTP status codes for errors

• Choice of workflow: v11 multi-step or SearchComplete single call

Business Benefits:

• Faster development and time-to-market

• Reduced bandwidth and infrastructure costs

• Easier maintenance and debugging

• Better performance for end users

• Modern architecture supporting future enhancements

Recommendation:

For new implementations, we strongly recommend using SearchComplete API. It provides the simplest integration path with best performance. For existing v11 implementations, SearchComplete offers a clear upgrade path with significant benefits.

The Travelport team is available to assist with your migration. Contact your account manager or visit the developer portal for additional resources and support.

Document Feedback

We value your feedback on this documentation. If you have suggestions for improvements, find errors, or need clarification on any topic, please contact:

• Your Travelport Account Manager

• Travelport Support team

• Developer Portal feedback form

For urgent API issues or production support, contact Travelport support immediately.